<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Eigen: Interfacing with raw buffers: the Map class</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
  $(document).ready(function() { init_search(); });
/* @license-end */
</script>
<script type="text/x-mathjax-config">
  MathJax.Hub.Config({
    extensions: ["tex2jax.js", "TeX/AMSmath.js", "TeX/AMSsymbols.js"],
    jax: ["input/TeX","output/HTML-CSS"],
});
</script>
<script type="text/javascript" async="async" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="eigendoxy.css" rel="stylesheet" type="text/css">
<!--  -->
<script type="text/javascript" src="eigen_navtree_hacks.js"></script>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="Eigen_Silly_Professor_64x64.png"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname"><a href="http://eigen.tuxfamily.org">Eigen</a>
   &#160;<span id="projectnumber">3.4.90 (git rev 67eeba6e720c5745abc77ae6c92ce0a44aa7b7ae)</span>
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.svg"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('group__TutorialMapClass.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Interfacing with raw buffers: the Map class<div class="ingroups"><a class="el" href="group__DenseMatrixManipulation__chapter.html">Dense matrix and array manipulation</a></div></div>  </div>
</div><!--header-->
<div class="contents">
<p>This page explains how to work with "raw" C/C++ arrays. This can be useful in a variety of contexts, particularly when "importing" vectors and matrices from other libraries into Eigen.</p>
<h1><a class="anchor" id="TutorialMapIntroduction"></a>
Introduction</h1>
<p>Occasionally you may have a pre-defined array of numbers that you want to use within Eigen as a vector or matrix. While one option is to make a copy of the data, most commonly you probably want to re-use this memory as an Eigen type. Fortunately, this is very easy with the <a class="el" href="classEigen_1_1Map.html" title="A matrix or vector expression mapping an existing array of data.">Map</a> class.</p>
<h1><a class="anchor" id="TutorialMapTypes"></a>
Map types and declaring Map variables</h1>
<p>A <a class="el" href="classEigen_1_1Map.html" title="A matrix or vector expression mapping an existing array of data.">Map</a> object has a type defined by its Eigen equivalent: </p><div class="fragment"><div class="line">Map&lt;Matrix&lt;typename Scalar, int RowsAtCompileTime, int ColsAtCompileTime&gt; &gt;</div>
</div><!-- fragment --><p> Note that, in this default case, a <a class="el" href="classEigen_1_1Map.html" title="A matrix or vector expression mapping an existing array of data.">Map</a> requires just a single template parameter. <br  />
</p>
<p>To construct a <a class="el" href="classEigen_1_1Map.html" title="A matrix or vector expression mapping an existing array of data.">Map</a> variable, you need two other pieces of information: a pointer to the region of memory defining the array of coefficients, and the desired shape of the matrix or vector. For example, to define a matrix of <code>float</code> with sizes determined at compile time, you might do the following: </p><div class="fragment"><div class="line">Map&lt;MatrixXf&gt; mf(pf,rows,columns);</div>
</div><!-- fragment --><p> where <code>pf</code> is a <code>float</code> <code>*</code> pointing to the array of memory. A fixed-size read-only vector of integers might be declared as </p><div class="fragment"><div class="line">Map&lt;const Vector4i&gt; mi(pi);</div>
</div><!-- fragment --><p> where <code>pi</code> is an <code>int</code> <code>*</code>. In this case the size does not have to be passed to the constructor, because it is already specified by the Matrix/Array type.</p>
<p>Note that <a class="el" href="classEigen_1_1Map.html" title="A matrix or vector expression mapping an existing array of data.">Map</a> does not have a default constructor; you <em>must</em> pass a pointer to initialize the object. However, you can work around this requirement (see <a class="el" href="group__TutorialMapClass.html#TutorialMapPlacementNew">Changing the mapped array</a>).</p>
<p><a class="el" href="classEigen_1_1Map.html" title="A matrix or vector expression mapping an existing array of data.">Map</a> is flexible enough to accommodate a variety of different data representations. There are two other (optional) template parameters: </p><div class="fragment"><div class="line">Map&lt;<span class="keyword">typename</span> MatrixType,</div>
<div class="line">    <span class="keywordtype">int</span> MapOptions,</div>
<div class="line">    <span class="keyword">typename</span> StrideType&gt;</div>
</div><!-- fragment --> <ul>
<li><code>MapOptions</code> specifies whether the pointer is <code><a class="el" href="group__enums.html#gga45fe06e29902b7a2773de05ba27b47a1ae12d0f8f869c40c76128260af2242bc8">Aligned</a></code>, or <code><a class="el" href="group__enums.html#gga45fe06e29902b7a2773de05ba27b47a1a4e19dd09d5ff42295ba1d72d12a46686">Unaligned</a></code>. The default is <code><a class="el" href="group__enums.html#gga45fe06e29902b7a2773de05ba27b47a1a4e19dd09d5ff42295ba1d72d12a46686">Unaligned</a></code>. </li>
<li><code>StrideType</code> allows you to specify a custom layout for the memory array, using the <a class="el" href="classEigen_1_1Stride.html" title="Holds strides information for Map.">Stride</a> class. One example would be to specify that the data array is organized in row-major format: <table class="example">
<tr>
<th>Example:</th><th>Output: </th></tr>
<tr>
<td><div class="fragment"><div class="line"><span class="keywordtype">int</span> array[8];</div>
<div class="line"><span class="keywordflow">for</span>(<span class="keywordtype">int</span> i = 0; i &lt; 8; ++i) array[i] = i;</div>
<div class="line">cout &lt;&lt; <span class="stringliteral">&quot;Column-major:\n&quot;</span> &lt;&lt; Map&lt;Matrix&lt;int,2,4&gt; &gt;(array) &lt;&lt; endl;</div>
<div class="line">cout &lt;&lt; <span class="stringliteral">&quot;Row-major:\n&quot;</span> &lt;&lt; Map&lt;Matrix&lt;int,2,4,RowMajor&gt; &gt;(array) &lt;&lt; endl;</div>
<div class="line">cout &lt;&lt; <span class="stringliteral">&quot;Row-major using stride:\n&quot;</span> &lt;&lt;</div>
<div class="line">  Map&lt;Matrix&lt;int,2,4&gt;, <a class="code" href="group__enums.html#gga45fe06e29902b7a2773de05ba27b47a1a4e19dd09d5ff42295ba1d72d12a46686">Unaligned</a>, Stride&lt;1,4&gt; &gt;(array) &lt;&lt; endl;</div>
<div class="line"> </div>
<div class="ttc" id="agroup__enums_html_gga45fe06e29902b7a2773de05ba27b47a1a4e19dd09d5ff42295ba1d72d12a46686"><div class="ttname"><a href="group__enums.html#gga45fe06e29902b7a2773de05ba27b47a1a4e19dd09d5ff42295ba1d72d12a46686">Eigen::Unaligned</a></div><div class="ttdeci">@ Unaligned</div><div class="ttdef"><b>Definition:</b> Constants.h:235</div></div>
</div><!-- fragment -->  </td><td><pre class="fragment">Column-major:
0 2 4 6
1 3 5 7
Row-major:
0 1 2 3
4 5 6 7
Row-major using stride:
0 1 2 3
4 5 6 7
</pre>  </td></tr>
</table>
However, <a class="el" href="classEigen_1_1Stride.html" title="Holds strides information for Map.">Stride</a> is even more flexible than this; for details, see the documentation for the <a class="el" href="classEigen_1_1Map.html" title="A matrix or vector expression mapping an existing array of data.">Map</a> and <a class="el" href="classEigen_1_1Stride.html" title="Holds strides information for Map.">Stride</a> classes.</li>
</ul>
<h1><a class="anchor" id="TutorialMapUsing"></a>
Using Map variables</h1>
<p>You can use a <a class="el" href="classEigen_1_1Map.html" title="A matrix or vector expression mapping an existing array of data.">Map</a> object just like any other Eigen type: </p><table class="example">
<tr>
<th>Example:</th><th>Output: </th></tr>
<tr>
<td><div class="fragment"><div class="line"><span class="keyword">typedef</span> Matrix&lt;float,1,Dynamic&gt; MatrixType;</div>
<div class="line"><span class="keyword">typedef</span> Map&lt;MatrixType&gt; MapType;</div>
<div class="line"><span class="keyword">typedef</span> Map&lt;const MatrixType&gt; MapTypeConst;   <span class="comment">// a read-only map</span></div>
<div class="line"><span class="keyword">const</span> <span class="keywordtype">int</span> n_dims = 5;</div>
<div class="line">  </div>
<div class="line">MatrixType m1(n_dims), m2(n_dims);</div>
<div class="line">m1.setRandom();</div>
<div class="line">m2.setRandom();</div>
<div class="line"><span class="keywordtype">float</span> *p = &amp;m2(0);  <span class="comment">// get the address storing the data for m2</span></div>
<div class="line">MapType m2map(p,m2.size());   <span class="comment">// m2map shares data with m2</span></div>
<div class="line">MapTypeConst m2mapconst(p,m2.size());  <span class="comment">// a read-only accessor for m2</span></div>
<div class="line"> </div>
<div class="line">cout &lt;&lt; <span class="stringliteral">&quot;m1: &quot;</span> &lt;&lt; m1 &lt;&lt; endl;</div>
<div class="line">cout &lt;&lt; <span class="stringliteral">&quot;m2: &quot;</span> &lt;&lt; m2 &lt;&lt; endl;</div>
<div class="line">cout &lt;&lt; <span class="stringliteral">&quot;Squared euclidean distance: &quot;</span> &lt;&lt; (m1-m2).squaredNorm() &lt;&lt; endl;</div>
<div class="line">cout &lt;&lt; <span class="stringliteral">&quot;Squared euclidean distance, using map: &quot;</span> &lt;&lt;</div>
<div class="line">  (m1-m2map).squaredNorm() &lt;&lt; endl;</div>
<div class="line">m2map(3) = 7;   <span class="comment">// this will change m2, since they share the same array</span></div>
<div class="line">cout &lt;&lt; <span class="stringliteral">&quot;Updated m2: &quot;</span> &lt;&lt; m2 &lt;&lt; endl;</div>
<div class="line">cout &lt;&lt; <span class="stringliteral">&quot;m2 coefficient 2, constant accessor: &quot;</span> &lt;&lt; m2mapconst(2) &lt;&lt; endl;</div>
<div class="line"><span class="comment">/* m2mapconst(2) = 5; */</span>   <span class="comment">// this yields a compile-time error</span></div>
</div><!-- fragment -->  </td><td><pre class="fragment">m1:   0.68 -0.211  0.566  0.597  0.823
m2: -0.605  -0.33  0.536 -0.444  0.108
Squared euclidean distance: 3.26
Squared euclidean distance, using map: 3.26
Updated m2: -0.605  -0.33  0.536      7  0.108
m2 coefficient 2, constant accessor: 0.536
</pre>  </td></tr>
</table>
<p>All Eigen functions are written to accept <a class="el" href="classEigen_1_1Map.html" title="A matrix or vector expression mapping an existing array of data.">Map</a> objects just like other Eigen types. However, when writing your own functions taking Eigen types, this does <em>not</em> happen automatically: a <a class="el" href="classEigen_1_1Map.html" title="A matrix or vector expression mapping an existing array of data.">Map</a> type is not identical to its <a class="el" href="structEigen_1_1Dense.html">Dense</a> equivalent. See <a class="el" href="TopicFunctionTakingEigenTypes.html">Writing Functions Taking Eigen Types as Parameters</a> for details.</p>
<h1><a class="anchor" id="TutorialMapPlacementNew"></a>
Changing the mapped array</h1>
<p>It is possible to change the array of a <a class="el" href="classEigen_1_1Map.html" title="A matrix or vector expression mapping an existing array of data.">Map</a> object after declaration, using the C++ "placement new" syntax: </p><table class="example">
<tr>
<th>Example:</th><th>Output: </th></tr>
<tr>
<td><div class="fragment"><div class="line"><span class="keywordtype">int</span> data[] = {1,2,3,4,5,6,7,8,9};</div>
<div class="line">Map&lt;RowVectorXi&gt; v(data,4);</div>
<div class="line">cout &lt;&lt; <span class="stringliteral">&quot;The mapped vector v is: &quot;</span> &lt;&lt; v &lt;&lt; <span class="stringliteral">&quot;\n&quot;</span>;</div>
<div class="line"><span class="keyword">new</span> (&amp;v) Map&lt;RowVectorXi&gt;(data+4,5);</div>
<div class="line">cout &lt;&lt; <span class="stringliteral">&quot;Now v is: &quot;</span> &lt;&lt; v &lt;&lt; <span class="stringliteral">&quot;\n&quot;</span>;</div>
</div><!-- fragment -->  </td><td><pre class="fragment">The mapped vector v is: 1 2 3 4
Now v is: 5 6 7 8 9
</pre>  </td></tr>
</table>
<p>Despite appearances, this does not invoke the memory allocator, because the syntax specifies the location for storing the result.</p>
<p>This syntax makes it possible to declare a <a class="el" href="classEigen_1_1Map.html" title="A matrix or vector expression mapping an existing array of data.">Map</a> object without first knowing the mapped array's location in memory: </p><div class="fragment"><div class="line">Map&lt;Matrix3f&gt; A(NULL);  <span class="comment">// don&#39;t try to use this matrix yet!</span></div>
<div class="line"><a class="code" href="group__matrixtypedefs.html#ga8028d921d43acd5605eabad41c254ef2">VectorXf</a> b(n_matrices);</div>
<div class="line"><span class="keywordflow">for</span> (<span class="keywordtype">int</span> i = 0; i &lt; n_matrices; i++)</div>
<div class="line">{</div>
<div class="line">  <span class="keyword">new</span> (&amp;A) Map&lt;Matrix3f&gt;(get_matrix_pointer(i));</div>
<div class="line">  b(i) = A.trace();</div>
<div class="line">}</div>
<div class="ttc" id="agroup__matrixtypedefs_html_ga8028d921d43acd5605eabad41c254ef2"><div class="ttname"><a href="group__matrixtypedefs.html#ga8028d921d43acd5605eabad41c254ef2">Eigen::VectorXf</a></div><div class="ttdeci">Matrix&lt; float, Dynamic, 1 &gt; VectorXf</div><div class="ttdoc">Dynamic×1 vector of type float.</div><div class="ttdef"><b>Definition:</b> Matrix.h:500</div></div>
</div><!-- fragment --> </div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Thu Apr 21 2022 13:07:55 for Eigen by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.9.1 </li>
  </ul>
</div>
</body>
</html>
